<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
<HTML><HEAD>
		<TITLE>User's Guide - Understanding the Script Structure</TITLE>
		<META HTTP-EQUIV="keywords" CONTENT="GRAPHICS VISUALIZATION VISUAL PROGRAM DATA
MINING">
	<meta http-equiv="content-type" content="text/html;charset=ISO-8859-1">
</HEAD><BODY BGCOLOR="#FFFFFF" link="#00004b" vlink="#4b004b">
		<TABLE width=510 border=0 cellpadding=0 cellspacing=0>
			<TR>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=80 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=49 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=24 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=100 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=3 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=127 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=6 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=50 HEIGHT=1></TD>
				<TD><IMG SRC="../images/spacer.gif" WIDTH=71 HEIGHT=1></TD>
			</TR>
			<TR>
				<TD colspan=9><IMG src="../images/flcgh_01.gif" width=510 height=24 border="0" alt="OpenDX - Documentation"></TD>
			</TR>
			<TR>
				<TD colspan=2><A href="../allguide.htm"><IMG src="../images/flcgh_02.gif" width=129 height=25 border="0" alt="Full Contents"></A></TD>
				<TD colspan=3><A href="../qikguide.htm"><IMG src="../images/flcgh_03.gif" width=127 height=25 border="0" alt="QuickStart Guide"></A></TD>
				<TD><A href="../usrguide.htm"><B><IMG src="../images/flcgh_04d.gif" width=127 height=25 border="0" alt="User's Guide"></B></A></TD>
				<TD colspan=3><A href="../refguide.htm"><IMG src="../images/flcgh_05.gif" width=127 height=25 border="0" alt="User's Reference"></A></TD>
			</TR>
			<TR>
				<TD><A href="usrgu050.htm"><IMG src="../images/flcgh_06.gif" width=80 height=17 border="0" alt="Previous Page"></A></TD>
				<TD colspan=2><A href="usrgu052.htm"><IMG src="../images/flcgh_07.gif" width=73 height=17 border="0" alt="Next Page"></A></TD>
				<TD><A href="../usrguide.htm"><IMG src="../images/flcgh_08.gif" width=100 height=17 border="0" alt="Table of Contents"></A></TD>
				<TD colspan=3><A href="usrgu050.htm"><IMG src="../images/flcgh_09.gif" width=136 height=17 border="0" alt="Partial Table of Contents"></A></TD>
				<TD><A href="usrgu080.htm"><IMG src="../images/flcgh_10.gif" width=50 height=17 border="0" alt="Index"></A></TD>
				<TD><A href="../srchindx.htm"><IMG SRC="../images/flcgh_11.gif" width=71 height=17 border="0" alt="Search"></A></TD>
			</TR>
		</TABLE>
		<H2><A NAME="HDRBASELM" ></A>10.2 Understanding the Script Structure
</H2>
		<P>
The following example illustrate some of the more important
characteristics of scripts;
a detailed description of each of the elements follows.
However, you may prefer to simply study these examples (and perhaps
those in /usr/local/dx/samples/scripts) and then begin writing your
own scripts.

		<P>
<H4><U>Example 1. A Simple Script</U></H4>
<P>
In this example, the data found in /usr/...cloudwater is imported and
assigned to the variable <TT><STRONG>data</STRONG></TT>.
Then the Isosurface module is called on <TT><STRONG>data</STRONG></TT> (with
no other parameters set)  and the result is assigned to
<TT><STRONG>iso</STRONG></TT>.
A Camera is created using AutoCamera, and the isosurface is displayed
using Display (note that the Image tool is not available in the
scripting language.
<PRE>
data = Import("/usr/local/dx/samples/data/cloudwater");
iso = Isosurface(data);
camera = AutoCamera(iso);
Display(iso, camera);
</PRE>
<P>
<H4><U>Example 2. Setting Parameters</U></H4>
<P>
Suppose that in the previous example we wished to set the Isosurface
"number" to 3.
<TT><STRONG>number</STRONG></TT> is the third parameter to Isosurface.
We can replace the second line of the script in Example 1 with:
<PRE>
iso = Isosurface(data, NULL, 3);
</PRE>
or, alternatively,
<PRE>
iso = Isosurface(data, number=3);
</PRE>
<P>
<H4><U>Example 3. Using a Macro</U></H4>
<P>
It is possible to create and use macros in the scripting language.
A macro is defined using the keyword "macro," as in
the following example.
<PRE>
macro make_iso(data, isovalue) -&gt; (isosurface)
{
   isosurface = Isosurface(data, isovalue);
}
</PRE>
To use the macro, simply call it with the required parameters:
<PRE>
iso1 = make_iso(data, 0.1);
iso2 = make_iso(data, 0.2);
...
</PRE>
<P>
A macro can have as many inputs or outputs as desired.
Note that it is not necessary to pass parameters into a macro; the
parameters will be found in the environment outside of the macro
if necessary.
However, it <I>is</I> necessary to pass any parameters
<I>out</I> of the macro that are intended to be used
outside of the macro.
<P>
<H4><U>Example 4. Using Route in the Script Language</U></H4>
<P>
The Route module is used to choose between different destinations for
a particular object.
For example, you could choose to either write an image to a file or
display the image to the screen.
<P>
In order to use Route in a script, the Route module and the tools that
consume the outputs of Route must be contained in a macro.
<PRE>
data = Import("/usr/local/dx/samples/data/cloudwater");
iso = Isosurface(data);
camera = Autocamera(iso);
image= Render(iso, camera);
macro do_which(which, image)
{
   image_to_display, image_to_write = Route(which, image);
   Display(image_to_display);
   WriteImage(image_to_write);
}
do_which(1, image);
</PRE>
<P>
The call to the macro do_which with a value of 1 causes the first output
branch (Display) to be executed.
WriteImage is <I>not</I> executed.
If do_which had been called with a value of 2, however, then WriteImage
(and not Display) would have been executed.
<P>
<H4><U>Example 5. Using the Sequencer</U></H4>
<P>
You can use the Sequencer in script mode.
The special variables you use are:
<TABLE CELLPADDING="3">
<TR VALIGN="TOP"><TD><P><B>@startframe
</B></TD><TD><P>the starting integer of the sequence
</TD></TR><TR VALIGN="TOP"><TD><P><B>@endframe
</B></TD><TD><P>the ending integer of the sequence
</TD></TR><TR VALIGN="TOP"><TD><P><B>@deltaframe
</B></TD><TD><P>the increment between frames (default = 1)
</TD></TR><TR VALIGN="TOP"><TD><P><B>@frame
</B></TD><TD><P>contains the sequence number of the current frame.
</TD></TR></TABLE>
The keyword "sequence" identifies the macro that will be run each
time @frame is incremented, and the keyword "play" will start
the sequence.
<P>
The following script will call the macro "doit" with the values
0, 2, 4, 6, 8, 10:
<PRE>
@startframe =0;
@endframe =10;
@deltaframe =2;
macro doit(i)
{
   Echo(i);
}
sequence doit(@frame);
play;
</PRE>
		<P>
		<HR>
		<DIV align="center">
			<P><A href="../allguide.htm"><IMG src="../images/foot-fc.gif" width="94" height="18" border="0" alt="Full Contents"></A> <A href="../qikguide.htm"><IMG src="../images/foot-qs.gif" width="94" height="18" border="0" alt="QuickStart Guide"></A> <A href="../usrguide.htm"><IMG src="../images/foot-ug.gif" width="94" height="18" border="0" alt="User's Guide"></A> <A href="../refguide.htm"><IMG src="../images/foot-ur.gif" width="94" height="18" border="0" alt="User's Reference"></A></P>
		</DIV>
		<DIV align="center">
			<P><FONT size="-1">[ <A href="http://www.research.ibm.com/dx">OpenDX Home at IBM</A>&nbsp;|&nbsp;<A href="http://www.opendx.org/">OpenDX.org</A>&nbsp;] </FONT></P>
			<P></P>
		</DIV>
	</BODY></HTML>
